Setting up your development environment

So you want to use joeq? This guide gives step-by-step instructions on how to set up the joeq development environment. The instructions given here are by no means the only way to set up joeq; advanced users can, for example, use their own Java IDE or CVS client.

Essentials

First, make sure that your system meets the minimum specs for joeq. To successfully compile and use joeq, you'll need the following:

1. A supported Java Development Kit installed. I try to keep joeq working with the latest versions of Java 1.3, 1.4, and 1.5 available from Sun, and also the latest versions of the IBM Developer Kits. Other virtual machines have not been tested.

In addition, if you want to bootstrap joeq, you will need the following:

1. A machine with a supported CPU. Currently, the x86 family (and clones) are the only supported CPU types.
2. Enough RAM to complete the bootstrap phase (~512MB) and hard drive space for all of the joeq files (~100MB).
3. Unless you want to port the C loader module to your OS, you will need to use an OS that is supported by the C loader. Currently, the C loader has been tested on Win32 and Linux.
4. A C compiler (to compile the C loader module) and linker (to link the module to joeq). Most Linux systems have these by default. On Windows, you can use Microsoft Visual C++ or the mingw toolkit contained in cygwin.

Also, these are not strictly necessary, but highly recommended:

1. CVS and SSH, so that you can get the latest source tree. Download links and installation instructions are below.
2. An account on SourceForge, so you can check in your modifications to the source tree.
3. Eclipse, an open-source IDE, written in Java. It includes integrated CVS support, a source-level debugger, and other goodies. Installation instructions below.
4. If you want to be able to bootstrap from inside of Eclipse, 1GB RAM (or more) is highly recommended.
5. A decently fast machine (>1GHz), because compiling and bootstrapping joeq can take a long time.

"Hosted mode" versus "Native mode"

joeq supports two modes of operation: "hosted" and "native". In hosted mode, joeq runs on top of another virtual machine. Because joeq is written in Java, almost all of the code is VM-independent; it can run on any Java virtual machine that obeys the JVM specification. If you are just interested in using joeq as a compiler infrastructure, then you will only need to use hosted mode. Hosted mode relies on the resources of the underlying virtual machine for garbage collection, synchronization, thread scheduling, etc.

In native mode, joeq runs on its own, without another virtual machine below it. In native mode, joeq uses its own runtime routines for allocation/garbage collection, thread scheduler, etc. Thus, if you are interested in using or experimenting with the joeq runtime system, you will need to use native mode.

Native mode requires a bootstrapping phase, whereby joeq is first run in hosted mode and an object file is dumped out, which is then linked to create a standalone executable. The bootstrapping phase relies on the specifics of the internal implementation of the virtual machine used for bootstrapping. Thus, only certain virtual machine versions are supported.

I have tested joeq bootstrapping with the following versions:

• Windows:
  • Sun J2SE 1.3.1_15
  • Sun J2SE 1.4.2_06
  • Sun J2SE 5.0 Update 1
• Linux:
  • Sun J2SE 1.3.1_15
  • Sun J2SE 1.4.2_06
  • Sun J2SE 5.0 Update 1

Other versions and virtual machines may or may not work. I will only guarantee that I will try to keep joeq working with the latest versions of the JVM available from Sun. I will not attempt to support legacy versions.

Setting up Eclipse IDE with joeq

To set up the Eclipse IDE for use with joeq, follow the tutorial here.

Windows-specific instructions

First, if you don't have the Sun JDK installed yet, download version 1.4.2 from here and install it into the default directory. joeq uses Sun's JVM to bootstrap itself, and it also uses the Sun class libraries.

If your machine is low on physical memory, you can also use version 1.3.1, available here.

Note: other JVM's that do not use the Sun class libraries, like gcj, will probably not bootstrap correctly. They should run fine in hosted mode, however.

Installing Eclipse IDE on Win32

First, download the Eclipse IDE from here. The one I recommend downloading is listed as "Stable Build". Install it by extracting the archive to the root directory of your drive and double-clicking on the eclipse.exe program in the extracted eclipse/ directory. It will say "Please wait, completing the install..." and then drop you into the Eclipse IDE.